---
sidebar_position: 2
---

# withSpring

`withSpring` lets you create spring-based animations.

import SpringBasic from '@site/src/examples/SpringBasic';
import SpringBasicSrc from '!!raw-loader!@site/src/examples/SpringBasic';

<InteractiveExample src={SpringBasicSrc} component={SpringBasic} />

## Reference

```javascript
import { withSpring } from 'react-native-reanimated';

function App() {
  sv.value = withSpring(0);
  // ...
}
```

<details>
<summary>Type definitions</summary>

```typescript
type AnimatableValue = number | string | number[];

export type SpringConfig = {
  mass?: number;
  overshootClamping?: boolean;
  energyThreshold?: number;
  velocity?: number;
  reduceMotion?: ReduceMotion;
} & (
  | {
      stiffness?: number;
      damping?: number;
      duration?: never;
      dampingRatio?: never;
      clamp?: never;
    }
  | {
      stiffness?: never;
      damping?: never;
      duration?: number;
      dampingRatio?: number;
      clamp?: { min?: number; max?: number };
    }
);

function withSpring<T extends AnimatableValue>(
  toValue: T,
  config?: WithSpringConfig,
  callback?: (finished?: boolean, current?: AnimatableValue) => void
): T;

enum ReduceMotion {
  System = 'system',
  Always = 'always',
  Never = 'never',
}
```

</details>

### Arguments

#### `toValue`

import AnimationToValue from './_shared/animationToValue.mdx';

<AnimationToValue />

#### `config` <Optional />

The spring animation configuration.

import { useSpringPlayground } from '@site/src/components/InteractivePlayground';

<InteractivePlayground usePlayground={useSpringPlayground} />

Available for physics-based spring:

| Name                   | Type     | Default | Description                                                                                |
| ---------------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| damping <Optional />   | `number` | 120     | How quickly a spring slows down. Higher damping means the spring will come to rest faster. |
| stiffness <Optional /> | `number` | 900     | How bouncy the spring is.                                                                  |

Available for duration-based spring:

| Name                      | Type     | Default | Description                                                                                                                                                          |
| ------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| duration <Optional />     | `number` | 550     | Perceptual duration of the animation in milliseconds. Actual duration is 1.5 times the value of perceptual duration.                                                 |
| dampingRatio <Optional /> | `number` | 1       | How damped the spring is. Value `1` means the spring is critically damped, value `>1` means the spring is overdamped and value `<1` means the spring is underdamped. |

:::info
The `stiffness` and `damping` (physics-based) properties can't be used at the same time as `duration` and `dampingRatio` (duration-based).

When used together `duration` and `dampingRatio` overrides `stiffness` and `damping` props.
:::

Available for every spring animation:

| Name                           | Type               | Default               | Description                                                                                                                                   |
| ------------------------------ | ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| mass <Optional />              | `number`           | 4                     | The weight of the spring. Reducing this value makes the animation faster.                                                                     |
| velocity <Optional />          | `number`           | 0                     | Initial velocity applied to the spring equation.                                                                                              |
| overshootClamping <Optional /> | `boolean`          | false                 | Whether a spring can bounce over the `toValue`.                                                                                               |
| energyThreshold <Optional />   | `number`           | 6e-9                  | Relative energy threshold below which the spring will snap without further oscillations.                                                      |
| reduceMotion <Optional />      | `ReduceMotion`     | `ReduceMotion.System` | A parameter that determines how the animation responds to the device's reduced motion accessibility setting.                                  |
| clamp <Optional />             | `[number, number]` | `undefined`           | Limit of the scope of movement. If your spring would exceed this limit, then `dampingRatio` will be reduced (to make the spring less bouncy). |

#### `callback` <Optional />

A function called upon animation completion. If the animation is cancelled, the callback will receive `false` as the argument; otherwise, it will receive `true`.

### Returns

`withSpring` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](/docs/core/useAnimatedStyle).

## Example

import SpringCarousel from '@site/src/examples/SpringCarousel';
import SpringCarouselSrc from '!!raw-loader!@site/src/examples/SpringCarousel';

<InteractiveExample src={SpringCarouselSrc} component={SpringCarousel} />

## Remarks

- The callback passed to the 3rd argument is automatically [workletized](/docs/fundamentals/glossary#to-workletize) and ran on the [UI thread](/docs/fundamentals/glossary#ui-thread).

## Platform compatibility

<PlatformCompatibility android ios web />
